import { snippets } from "@/lib/generated/snippets";
import { Snippet } from "@/components/code";
import { Callout, Card, Cards, Steps, Tabs } from "nextra/components";
import UniversalTabs from "@/components/UniversalTabs";

# Run on Event

> This example assumes we have a [task](./your-first-task.mdx) registered on a running [worker](./workers.mdx).

Run-on-event allows you to trigger one or more tasks when a specific event occurs. This is useful when you need to execute a task in response to an ephemeral event where the result is not important. A few common use cases for event-triggered task runs are:

1. Running a task when an ephemeral event is received, such as a webhook or a message from a queue.
2. When you want to run multiple independent tasks in response to a single event. For instance, if you wanted to run a `send_welcome_email` task, and you also wanted to run a `grant_new_user_credits` task, and a `reward_referral` task, all triggered by the signup. In this case, you might declare all three of those tasks with an event trigger for `user:signup`, and then have them all kick off when that event happens.

<Callout type="info">
  Event triggers evaluate tasks to run at the time of the event. If an event is
  received before the task is registered, the task will not be run.
</Callout>

## Declaring Event Triggers

To run a task on an event, you need to declare the event that will trigger the task. This is done by declaring the `on_events` property in the task declaration.

<UniversalTabs items={["Python", "Typescript", "Go"]}>
  <Tabs.Tab title="Python">
    <Snippet src={snippets.python.events.worker.event_trigger} />
  </Tabs.Tab>
  <Tabs.Tab title="Typescript">
    <Snippet
      src={snippets.typescript.on_event.workflow.run_workflow_on_event}
    />
  </Tabs.Tab>
  <Tabs.Tab title="Go">
    <Snippet src={snippets.go.on_event.main.run_workflow_on_event} />
  </Tabs.Tab>
</UniversalTabs>

<Callout type="info">
  Note: Multiple tasks can be triggered by the same event.
</Callout>

<Callout type="info">
  As of engine version 0.65.0, Hatchet supports wildcard event triggers using
  the `*` wildcard pattern. For example, you could register `subscription:*` as
  your event key, which would match incoming events like `subcription:create`,
  `subscription:renew`, `subscription:cancel`, and so on.
</Callout>

### Pushing an Event

You can push an event to the event queue by calling the `push` method on the Hatchet event client and providing the event name and payload.

<UniversalTabs items={["Python", "Typescript", "Go"]}>
  <Tabs.Tab title="Python">
    <Snippet src={snippets.python.events.event.event_trigger} />
  </Tabs.Tab>
  <Tabs.Tab title="Typescript">
    <Snippet src={snippets.typescript.on_event.event.pushing_an_event} />
  </Tabs.Tab>
  <Tabs.Tab title="Go">
    <Snippet src={snippets.go.on_event.main.pushing_an_event} />
  </Tabs.Tab>
</UniversalTabs>

## Event Filtering

Events can also be _filtered_ in Hatchet, which allows you to push events to Hatchet and only trigger task runs from them in certain cases. **If you enable filters on a workflow, your workflow will be triggered once for each matching filter on any incoming event with a matching scope** (more on scopes below).

### Basic Usage

There are two ways to create filters in Hatchet.

#### Default filters on the workflow

The simplest way to create a filter is to register it declaratively with your workflow when it's created. For example:

<UniversalTabs items={["Python", "Typescript", "Go"]}>
  <Tabs.Tab title="Python">
    <Snippet src={snippets.python.events.worker.event_trigger_with_filter} />
  </Tabs.Tab>
  <Tabs.Tab title="Typescript">
    <Snippet src={snippets.typescript.on_event.workflow.workflow_with_filter} />
  </Tabs.Tab>
  <Tabs.Tab title="Go">
    <Snippet src={snippets.go.on_event.main.declare_with_filter} />
  </Tabs.Tab>
</UniversalTabs>

In each of these cases, we register a filter with the workflow. Note that these "declarative" filters are overwritten each time your workflow is updated, so the ids associated with them will not be stable over time. This allows you to modify a filter in-place or remove a filter, and not need to manually delete it over the API.

#### Filters feature client

You also can create event filters by using the `filters` clients on the SDKs:

<UniversalTabs items={["Python", "Typescript", "Go"]}>
  <Tabs.Tab title="Python">
    <Snippet src={snippets.python.events.filter.create_a_filter} />
  </Tabs.Tab>
  <Tabs.Tab title="Typescript">
    <Snippet src={snippets.typescript.on_event.filter.create_a_filter} />
  </Tabs.Tab>
  <Tabs.Tab title="Go">
    <Snippet src={snippets.go.on_event.main.create_a_filter} />
  </Tabs.Tab>
</UniversalTabs>

<Callout type="warning">
  Note the `scope` argument to the filter. When you create a filter, it must be
  given a `scope` which will be used by Hatchet internally to look it up. When
  you push events that you want filtered, you **must provide a `scope` with
  those events that matches the scope sent with the filter**. If you do not, the
  filter will not apply.
</Callout>

Then, push an event that uses the filter to determine whether or not to run. For instance, this run will be skipped, since the payload does not match the expression:

<UniversalTabs items={["Python", "Typescript", "Go"]}>
  <Tabs.Tab title="Python">
    <Snippet src={snippets.python.events.filter.skip_a_run} />
  </Tabs.Tab>
  <Tabs.Tab title="Typescript">
    <Snippet src={snippets.typescript.on_event.filter.skip_a_run} />
  </Tabs.Tab>
  <Tabs.Tab title="Go">
    <Snippet src={snippets.go.on_event.main.skip_a_run} />
  </Tabs.Tab>
</UniversalTabs>

But this one will be triggered since the payload _does_ match the expression:

<UniversalTabs items={["Python", "Typescript", "Go"]}>
  <Tabs.Tab title="Python">
    <Snippet src={snippets.python.events.filter.trigger_a_run} />
  </Tabs.Tab>
  <Tabs.Tab title="Typescript">
    <Snippet src={snippets.typescript.on_event.filter.trigger_a_run} />
  </Tabs.Tab>
  <Tabs.Tab title="Go">
    <Snippet src={snippets.go.on_event.main.trigger_a_run} />
  </Tabs.Tab>
</UniversalTabs>

<Callout type="info">
  In Hatchet, filters are "positive", meaning that we look for _matches_ to the
  filter to determine which tasks to trigger.
</Callout>

### Accessing the filter payload

You can access the filter payload by using the `Context` in the task that was triggered by your event:

<UniversalTabs items={["Python", "Typescript", "Go"]}>
  <Tabs.Tab title="Python">
    <Snippet src={snippets.python.events.worker.accessing_the_filter_payload} />
  </Tabs.Tab>
  <Tabs.Tab title="Typescript">
    <Snippet
      src={snippets.typescript.on_event.workflow.accessing_the_filter_payload}
    />
  </Tabs.Tab>
  <Tabs.Tab title="Go">
    <Snippet src={snippets.go.on_event.main.accessing_the_filter_payload} />
  </Tabs.Tab>
</UniversalTabs>

### Advanced Usage

In addition to referencing `input` in the expression (which corresponds to the _event_ payload), you can also reference the following fields:

1. `payload` corresponds to the _filter_ payload (which was part of the request when the filter was created).
2. `additional_metadata` allows for filtering based on `additional_metadata` sent with the event.
3. `event_key` allows for filtering based on the key of the event, such as `user:created`.
